home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
EnigmA Amiga Run 1996 June
/
EnigmA AMIGA RUN 08 (1996)(G.R. Edizioni)(IT)[!][issue 1996-06][EARSAN CD VII].iso
/
earcd
/
comm2
/
xscan114.lha
/
DOC
/
XScan.doc
Wrap
Text File
|
1995-08-27
|
19KB
|
452 lines
XScan - Generic Packet Scanner for the Amiga
Copyright (c) 1995 by Robert Williamson, FIDONET#1:167/104.0
ALL RIGHTS RESERVED
This software is provided "as is", without warranty and/or
guarantee of any kind. You may use and/or distribute this software
and copies of it, as long as no alterations have been made, no files
have been added to/omitted from the original distribution archive
and no charge is asked for.
This package may be freely distributed via BBSs, ADS, AmiNet and
software libraries such as Fred Fish's and Aminet CD-ROMs, and other
similar electronic channels.
This package may NOT be distributed by SAN or by Disk magazines,
PD libraries or BBSs and Services that charge extra for file
transfers without authorization from, and compensation to the
author.
What is XScan?
XScan is a packet scanner which reads packets and creates a formatted
output of all messages found that are addressed to one the configured
Robot programs or aliases.
Robot is a generic term used to describe classes of programs such as
Area Managers, File Forwarders and FileFind programs. By providing for
configurable output formats, parameter expansion, aliases and formatting
of both message body and subject line style area manager commands, XScan
removes the need for packet scanning code within Robots. XScan also
permits complete independance from the local message base format and
removes the need for multiple passes on the same packet for multiple
Robot programs.
XScan was designed to meet my needs and those of my own software,
including the XRaid fileecho area manager, the AreaMGR echo area manager
and the FQuery FileFind program. However, it has been designed in a
manner that will hopefully make it useful for other Robot programs that
can read a list.
Status of This Release:
This is BETA and given the great number of features it probably has
bugs. In the case of a serious ERROR, and if the error conditions allow,
the error message will be logged. Please forward this information to
myself at either:
FIDONET#1:167/104.0 or AMIGANET#40:600/104.0.
BE SURE that you have set these addresses as ROUTED in your tosser or
packer/router config , so as not to incure long-distance charges.
The LogLevel for log messages is presently set quite low in order to
display a lot of progress info for debugging. At a LOGLEVEL of 3, the
log will grow very fast. At a later date, loglevels will be changed to
insure a minimal amount of info for normal processing.
This documentation may not be always up to date, as features are being
added at a very quick pace. Refer to the example XSCAN.cfg for config
changes and the XSCAN usage display for command line changes.
The ToDo list is changed daily, items being either implemented and
removed from the list or new items added. There is no obligation on my
part to implement anything in the ToDO list unless a contract to do so is
entered into by myself and a customer.
Copyrights:
XSCAN, XSCAN.doc and the format of XSCAN.cfg are all,
Copyright (c) 1995 by Robert Williamson, FIDONET#1:167/104.0
Why did I write it?
Simply because I found that my system was getting much too busy,
scanning each packet over and over for messages to XRAID, FQUERY and
other Robots as well as scanning my netmail directories on every import.
XScan allows me the luxury of scanning my packets ONLY ONCE and permitted
me to drop the Robot scanning code from my NetMGR.
Requirements:
WB 2.1 MINIMUM
rexxdossupport.library v2.3
The AmigaOS command Protect must be either resident or on the path.
XScan uses a STACK of 64K (yup..buffered i/o ON the stack) when
scanning packets. It restores the stack to original value when it
exits.
XScan sets the Archive bit on each packet it scans.
Features:
o pure, residentable
o multi-ftn
o independant of tosser and message base type
o handles both netmail and echomail
o configurable robot names, aliases, output format
o extensive parameter substitution
o does not modify the packets
Installation:
Be sure that your dearc command preserves attributes. If it does not,
run:
> Protect Mail:XSCAN pwerd
Copy XScan to somewhere on your path, MAIL: is nice. For faster
loading, you can pre-load it as resident with these commands:
> Resident Mail:XScan ADD
Make sure you REMOVE or REPLACE the old resident version when
upgrading and that you do not have any other program called XScan on your
path.
If you do not have a CFG: assign, create one and place your XScan.CFG
there. Otherwise, you will have to specify the CFG path on the
commandline. If you are going to do it anyways, then a good idea is to
copy the config to RAM: in your startup and use
CFG RAM:XScan.CFG
in your XScan command lines. This will speed up operations as bit more.
Copy rexxdossupport.library and rexxplslib.library to any directory of
your LIBS: assign.
Copy Start-ARexx to S:. Then remove the call to RexxMast in your
S:Startup-Sequence and add a call to S:Start-ARexx to your S:User-Startup.
Copy RPStart#? to your SYS:WBstartup directory.
When to Scan packets:
Packet scanning can be done a number of ways. Whichever method you
choose, it is your responsibiity to insure you do not scan the same
packet more than once.
The BEST way to run XSCAN (or any packet scanner, for that matter) is
from a CRON, once a day, just before midnight, from a directory that
contains backups of all packets received.
Run >NIL: XScan SCANDIR $(indir) AGE 0
This is how I do it. My tossing software allows me to backup packets
before tossing, even those within archives, and trim the backups by age.
Another method would be to export all mail to a dummy point and scan
those packets. This method is inefficient and a waste of disk space.
An alternate method would be to scan each packet BEFORE importing.
While this is trivial for packets received, when dealing with ArcMail,
this method would require one of:
- a tosser that allows you to configure a command to execute between
de-arcing and tossing
- modification of your dearc command to call XSCAN before returning
to the tosser
- some other trick you may come up with :)
Templates:
XScan uses standard AmigaDos Templates for both command line arguments
and for many configuration items. See the example XSCAN.CFG for
explanation of templates used in the config file.
Command Line Usage:
The various modes allows use of XScan in WhenRecd, TurnAround and
AfterSession commands as well as in a cli. The template is divided into
functional sets. A Set is defined by the first or base parameter.
DEBUG, LOGLEVEL and CFG may be used with any set, but may not be the
last items in the command line if a /F template is specified in the set.
Template parameters that are not valid for the set are ignored. The
template below shows each Set.
Template:
CFG/K,LOGLEVEL/K,SHOWCFG/S,DEBUG/S,NOEXE/S,XLATE/S
SCANDIR/K,AGE/K,PKTS/K/F
Commands
SHOWCFG [CFG file] [LOGLEVEL level] [DEBUG]
Displays configuration
SCANDIR directory [AGE day] [CFG file] [LOGLEVEL level] [DEBUG] [FORCE]
directory is scanned for all PKTs less or equal to AGE
[CFG file] [LOGLEVEL level] [DEBUG] [FORCE] PKTS filename...filename
the specified PKTs are scanned
Modifiers
AGE number of days, the maximum age of packets to scan
Default is 0 for packets received today, maximum is 30.
Applies only to SCANDIR.
FORCE forces rescanning of already scanned packets
Applies only to SCANDIR and PKTS
XLATE If XLATE is specified on the command line, AreaFix/Raid
dash-style command found in the subject are translated to
AreaMGR %-style commands.
CFG fullpathname of config file
Default is CFG:XSCAN.CFG
LOGLEVEL Overides configured default and scan program loglevels
level must be between 0 and 9
DEBUG extremely verbose mode, also forces loglevel to 9
NOEXE Disables execution of EXE ad REXXMSG commands.
This applies to SCANDIR and PKTS. Use this switch to perform
a scan and list to debug your ECHOFMT and NETFMT parameters.
examples
XScan CFG cfg:FQ.cfg PKTS audit:35656187.pkt inbound:12567736.pkt
XScan SCANDIR Mail:Inbound AGE 2
XScan SHOWCFG CFG CFG:XScan.cfg
XScan NOEXE DEBUG PKTS t:test.pkt
Configuration:
See example XSCAN.CFG
Addressing:
Addresses can be specified in a number of formats in the config file,
the preferred being FQFA. The minimum acceptable is 3d (z:net/node.) for
FidoNet and FTNS listed in FTNLIST. All other FTNs must be specified as
5D or FQFA.
Address Formats:
FQFA - ftn#zone:net/node.point (all must be present)
5d - zone:net/node[.point]@ftn (if no point, 0 is assumed)
4d - zone:net/node.point
3d - zone:net/node
The LIST output file:
This is the file created for each program (SCAN in the config) on
behalf of which we are scanning the packets. The file is always opened
in APPEND mode. It is the responsibility of the SCAN program to delete
the LIST file when it has completed processing it. The format of each
line is defined for each SCAN name by the keywords NETFMT, ECHOFMT and
AMCMDSEP. The maximum length of an output line is 64K.
Parameter Expansion:
Parameter expansion can be used in the configuration items NETFMT,
ECHOFMT, EXE and REXXMSG. Not ethat for the last two, you are limited by
the 256 character command line limit. Parameter which upon expansion,
exceed this will be truncated by amigados.
Each expandable parameter is enclosed in «..» double-brakets (ALT-9 and
ALT-0). These may appear as 1/2 and top-left-corner, depending upon the
font you are using.
General Parameters
------------------
«pgm» name of this program
«tv» copyright text of this program
«sv» version of this program
«vv» VERS: string of this program
Packet Parameters
-----------------
«packet» fullpathname of packet file
«pktlen» length of packet in bytes
Parameters derived from Packet Header
-------------------------------------
«pktdate» date of creation of packet
format: dd.mm.yyyy" "hh:mm:ss
«prodlo» ftsc product code of packet creation program (lo)
«prodhi» ftsc product code of packet creation program (hi)
«prodver» version and revision of packet creation program
«prodname» Name of packet creation program (requires PRODFILE)
«prodtype» Type of packet creation program (requires PRODFILE)
«prodos» OS of packet creation program (requires PRODFILE)
«prodby» Author of packet creation program (requires PRODFILE)
«prodadr» Contact address of packet creation program author
(requires PRODFILE)
«fromsite» FQFA of sender of packet
Note that for echomail and routed netmail, this is the
address of your HUB.
«oftn» FTN of packet sender
«ozone» ZONE of packet sender
«onet» NET of packet sender
«onode» NODE of packet sender
«opoint» POINT of packet sender
«tosite» FQFA of packet destination
«dftn» FTN of packet destination
«dzone» ZONE of packet destination
«dnet» NET of packet destination
«dnode» NODE of packet destination
«dpoint» POINT of packet destination
Parameters derived from Packed Message Header
---------------------------------------------
«toadr» message net/node destination address
«toname» message to name
«fromadr» message net/node originating address
Note that in the case of echomail, this is your ECHOHUB,
not the originator of the message.
«fromname» message from name
«subject» message subject
«msgdate» message date
«cost» cost of message
«abits» attribute word in binary (16 bits)
«attrtext» attribute word as space-separated text string
Bit 0 Priv
Bit 1 Crash
Bit 2 Recd
Bit 3 Sent
Bit 4 Fatt
Bit 5 InTransit
Bit 6 Orphan
Bit 7 KillSent
Bit 8 Local
Bit 9 HoldForPickup
Bit 10 Tracked
Bit 11 FReq
Bit 12 ReceiptReq
Bit 13 IsReceipt
Bit 14 AuditReq
Bit 15 UpdateReq
Parameters derived from Body of Packed Message
----------------------------------------------
«msgtext» Contents of message excluding control lines, Origin and
Seen-Bys. CR is converted to soft-return (0x8d hex)
«intl» INTL control line contents (excludes control field name)
XScan recognizes this kludge both with and without a colon
«fmpt» FMPT control line contents (excludes control field name)
XScan recognizes this kludge both with and without a colon
«topt» TOPT control line contents (excludes control field name)
XScan recognizes this kludge both with and without a colon
«msgid» MSGID control line contents (excludes control field name)
«pid» PID control line contents (excludes control field name)
«via» VIA control line contents (excludes control field name)
This is the LAST via in message.
«tagname» AREA TAGNAME (excludes control field name)
«origin» ORIGIN control line contents (excludes control field name)
«morg» address as listed in ORIGIN control line
Parameters derived from the config for detected SCAN program name
-----------------------------------------------------------------
«scanprog» program name
«ECHOAREAS» echomail areas to be scanned
«ECHOALIAS» echomail aliases for program
«NETALIAS» netmail aliases for program
«list» fullpathname of the output listing for this SCAN
«adrfmt» obsolete
«logfile» currently selected LOGFILE
«loglevel» currently selected LOGLEVEL
«exe» command to execute may be used in the output list
in order to create an EXECUTE script.
eg:NETFMT «exe» «dst3d»|«fromname»|«subject»|«org5d»|«amcmds»
Constructed parameters
----------------------
«mtime» time message was processed
«mdate» date message was processed
«toprog» name of program to which message is addressed
This is the first word of «toname») returned as UPPERCASE
«password» This is only applicable to NETMAIL
This is the first word of «subject» returned as UPPERCASE
«afcmds» This is only applicable to NETMAIL
AreaFix/Raid type commands from SUBJECT of message, case is
NOT changed.
«amcmds» This is only applicable to NETMAIL
A list of FSC57-style AreaMGR commands that were found in
the body of the message. Each is separated with the
defined AMCMDSEP. These commands include all lines that
begin with '+', '-' or '%'.
«xlcmds» If XLATE is specified on the command line, AreaFix/Raid
dash-style command fun inthe subject line are translated to
AreaMGR %-style commands. This variable is the translated
commands.
«cline» The number of FSC57-style AreaMGR command lines that were
found in the body of the message.
«FAFQorg» origin address
«org5d»
«org3d»
«odm» FTN of originator (uppercase)
«ozn» zone of originator
«ont» net of originator
«ond» node of originator
«opt» point of originator
«fqfadst» destination address (ususally our own)
«dst5d»
«dst3d»
«ddm» FTN of destination (uppercase)
«dzn» zone of destination
«dnt» net of destination
«dnd» node of destination
«dpt» point of destination
Additional Developer Notes
There are many other undocumented expansion parameters. Ask and you
shall receive :)
Address Expansion:
«fqfadst» and «fqfaorg» are constructed FQFA addresses, using FTNLIST
to build a FQFA. (Fully Qualified FTN Address) The 3d and 5d versions of
org and dst (org3d,org5d,dst3d,dst5d) are derived from the FQFA versions.
For both 3d and 5d, the point number is not included if zero.
The FTNLIST in XSCAN.cfg is used for address expansion. The address is
determined by checking the packed message fields in the following order.
If an INTL kludge is present then the origin address and destination
addresses of that kludge is used. A check must be made for TOPT and FMPT
also, and the point number appended to the appropriate address if either
is found.
If there is no INTL control line and an ORIGIN control line is found,
the address in the Origin (morg) is used to build the originating fqfa.
If there is neither INTL nor ORIGIN, and the address in the MSGID
control line is an FTN address, it shall be used for the origin address.
If the FTN of the msgid is not an FTN address, the destination address
is set using our HOST AKA that is in the same FTN as the originator. If a
REPLY control line exists, the address therin is used to build the FQFA
destination.
If the FTN of the msgid is not an FTN address, the destination address
is set using our HOST AKA that is in the same FTN as the originator.
--more to come--